AVChatManager

Kind of class:class
Inherits from:none
Version:1.0.0
Author:The gotoAndPlay() Team
http://www.smartfoxserver.com
http://www.gotoandplay.it
Classpath:com.smartfoxserver.redbox.AVChatManager
File last modified:Tuesday, 08 July 2008, 08:07:04
SmartFoxServer's RedBox Audio/Video Chat Manager.
This class is responsible for audio/video chat implementation by means of the connection to the Red5 server.
The AVChatManager handles the chat workflow (send request, accept or refuse it, establish or stop connection, etc.) and the live streaming to/from the Red5 server.

NOTE: in the provided examples, avChatMan always indicates an AVChatManager instance.
Usage:
  • The AVChatManager class is useful to create one-on-one audio/video chats. Three chat modes are supported: receive-only, send-only or send-and-receive.
    In send-only and receive-only modes, the a/v chat requests are distinct: a user can watch a friend without sending his own stream, and vice versa (just like in Windows Live Messenger, when you click the webcam icons under the users' pictures).
    In send-and-receive mode, a single request includes both sending the user's own stream and receiving the friend's stream.
    The following workflow is suggested (to make it simpler the send-and-receive mode is considered; for the other modes the flow is the same, but two separate requests are needed).
    1. The current user click on an interface element to send the a/v chat request to a friend; usually a button in a private chat window is used.
    2. An invitation is sent to the recipient user by means of the sendChatRequest method; of course the recipient must be connected to SmartFoxServer (but not necessarily in the same room of the requester), otherwise the com.smartfoxserver.redbox.events.RedBoxChatEvent.onRecipientMissing event is fired on the requester's client.
    3. On the recipient's client the com.smartfoxserver.redbox.events.RedBoxChatEvent.onChatRequest event is fired: an invitation to send and receive the a/v stream is displayed, together with the interface elements to accept or decline it.
      If the recipient refuses the invitation, the refuseChatRequest method is called, which causes the com.smartfoxserver.redbox.events.RedBoxChatEvent.onChatRefused event to be fired on the requester's client and the interface to be adjusted accordingly.
    4. The recipient accepts the invitation: the acceptChatRequest method is called, which causes the com.smartfoxserver.redbox.events.RedBoxChatEvent.onChatStarted event to be fired on both the requester's and the recipient's clients.
    5. On both the requester's and the recipient's clients two Video objects are added to the stage to display the incoming stream and the user's own camera output.
    6. One of the two users involved in the chat clicks on an interface element to stop the a/v chat: the stopChat method is called and the com.smartfoxserver.redbox.events.RedBoxChatEvent.onChatStopped event is fired on the connected user's client, so that the Video objects can be removed from stage.
Events broadcasted to listeners:
  • RedBoxChatEvent with type: onAVConnectionInited
    • Dispatched when the connection to Red5 server has been established.
  • RedBoxChatEvent with type: onAVConnectionError
    • Dispatched when the connection to Red5 server can't be established.
  • RedBoxChatEvent with type: onChatRequest
    • Dispatched when an a/v chat request is received.
  • RedBoxChatEvent with type: onRecipientMissing
    • Dispatched when a chat request is sent, but the recipient is not available.
  • RedBoxChatEvent with type: onDuplicateRequest
    • Dispatched when a chat request is sent, but a mutual request has already been sent by the recipient.
  • RedBoxChatEvent with type: onChatRefused
    • Dispatched when an a/v chat request has been refused by the recipient.
  • RedBoxChatEvent with type: onChatStarted
    • Dispatched when an a/v chat session is started, after the recipient accepted the requester's invitation.
  • RedBoxChatEvent with type: onChatStopped
    • Dispatched when an a/v chat session is stopped.

Summary


Constructor
  • AVChatManager (red5Ip:String, debug:Boolean)
    • AVChatManager contructor.
Class properties
  • REQ_TYPE_SEND : String
    • Audio/video chat request type: "stream from requester to recipient".
  • REQ_TYPE_RECEIVE : String
    • Audio/video chat request type: "stream from recipient to requester".
  • REQ_TYPE_SEND_RECEIVE : String
    • Audio/video chat request type: "bi-directional stream".
Instance properties
  • isConnected : Boolean
    • The status of the connection to the Red5 server.
Instance methods
  • initAVConnection : Void
    • Initialize the audio/video connection.
  • destroy : Void
    • Destroy the AVChatManager instance.
  • getChatSession (sessionId:String) : ChatSession
    • Retrieve a com.smartfoxserver.redbox.data.ChatSession object instance.
  • sendChatRequest (type:String, recipientId:Number, enableCamera:Boolean, enableMicrophone:Boolean) : ChatSession
    • Send a request to start an audio/video chat.
  • refuseChatRequest (sessionId:String) : Void
    • Refuse an incoming request to start an audio/video chat.
  • acceptChatRequest (sessionId:String) : Void
    • Accept an incoming request to start an audio/video chat.
  • stopChat (sessionId:String) : Void
    • Stop an a/v chat session currently in progress.
  • addEventListener (type:String, listener:Function) : Void
    • Register a listener function in order to receive notification of a RedBox event.
  • removeEventListener (type:String, listener:Function) : Void
    • Remove a listener from the event dispatcher, to stop receiving notification of an event.

Constructor

AVChatManager

function AVChatManager (
red5Ip:String, debug:Boolean)

AVChatManager contructor.
The RedBox classes make an extensive use of the SmartFoxBits Connector's s event handler in order to communicate with SmartFoxServer.
To achieve this you should place the Connector on a frame before you use RedBox classes on the following frame(s) or to make sure that the Connector is on the lowest layer of the timeline, and set the "Load order" option in the Flash Publish Settings to "Bottom up".
Parameters:
red5Ip:
the Red5 server IP address.
debug :
turn on the debug messages (optional, default is false).
Throws:
Example:
  • The following example shows how to instantiate the AVChatManager class.
    var red5IpAddress:String = "127.0.0.1"
    
    var avChatMan:AVChatManager = new AVChatManager(red5IpAddress)

    see MyUserPropsNotSetException

Class properties

REQ_TYPE_RECEIVE

static REQ_TYPE_RECEIVE:String = "receive"
(read)

Audio/video chat request type: "stream from recipient to requester".
The requester would like to receive the recipient's live a/v stream.
See also:

REQ_TYPE_SEND

static REQ_TYPE_SEND:String = "send"
(read)

Audio/video chat request type: "stream from requester to recipient".
The requester would like to send his own live a/v stream to the recipient.
See also:

REQ_TYPE_SEND_RECEIVE

static REQ_TYPE_SEND_RECEIVE:String = "send&rcv"
(read)

Audio/video chat request type: "bi-directional stream".
The requester would like to establish a mutual live a/v connection.
See also:

Instance properties

isConnected

isConnected:Boolean
(read)

The status of the connection to the Red5 server.
If true, the connection to Red5 is currently available.

Instance methods

acceptChatRequest

function acceptChatRequest (
sessionId:String) : Void

Accept an incoming request to start an audio/video chat.
Calling this method causes the com.smartfoxserver.redbox.events.RedBoxChatEvent.onChatStarted event to be fired on both the requester and the recipient clients.
Parameters:
sessionId:
the id of the chat session request to be accepted (see com.smartfoxserver.redbox.data.ChatSession.id property).
Events broadcasted to listeners:
  • RedBoxChatEvent with type: onChatStarted
    • Dispatched when an a/v chat session is started, after the recipient accepted the requester's invitation.
Throws:
Example:
  • The following example shows how to accept a chat request.
    bt_accept.addEventListener("click", Delegate.create(this, DleonAcceptBtClick))
    
    // After receiving a chat request, its session id is saved and an "accept" button activated...
    
    function onAcceptBtClick(evt:MouseEvent):Void
    {
        avChatMan.acceptChatRequest(chatSessionId)
    }

addEventListener

function addEventListener (
type:String, listener:Function) : Void

Register a listener function in order to receive notification of a RedBox event.

If you no longer need an event listener, remove it by calling the removeEventListener method.

NOTE: use the Delegate.create() method when registering a listener, to keep right scope in your application.
Parameters:
type :
The event type you want to be notified of.
listener:
The listener function in your application that processes the event. This function must accept an RedBoxChatEvent object as its only parameter and must return nothing, as in the example above.
Usage:
  • To register to an event:
    import com.smartfoxserver.redbox.events.*
    import mx.utils.Delegate
    
    avChatMan.addEventListener(RedBoxChatEvent.onChatRequest, Delegate.create(this, myListener))
    
    private function myListener(evt:RedBoxChatEvent):Void
    {
        trace("Got the event!")
        trace("Event type: " + evt.type)
        trace("Event target: " + evt.target)
        trace("Additional parameters:")
    
        for (var i in evt.params)
            trace("\t" + i + " -> " + evt.params[i])
    }

destroy

function destroy (
) : Void

Destroy the AVChatManager instance.
Calling this method causes the interruption of all chat sessions currently in progress (if any) and the disconnection from Red5.
This method should always be called before deleting the AVChatManager instance.
Example:
  • The following example shows how to destroy the AVChatManager instance.
    avChatMan.destroy()
    avChatMan = null

getChatSession

function getChatSession (
sessionId:String) : ChatSession

Retrieve a com.smartfoxserver.redbox.data.ChatSession object instance.
Parameters:
sessionId:
the id of the chat session to be retrieved (see com.smartfoxserver.redbox.data.ChatSession.id property).
Example:
  • The following example shows how to get a chat session.
    var chatData:ChatSession = avChatMan.getChatSession(sessionId)
    
    if (chatData != null)
        trace (chatData.toString())

initAVConnection

function initAVConnection (
) : Void

Initialize the audio/video connection.
Calling this method causes the connection to Red5 to be established and the com.smartfoxserver.redbox.events.RedBoxChatEvent.onAVConnectionInited event to be fired in response.
If the connection can't be established, the com.smartfoxserver.redbox.events.RedBoxChatEvent.onAVConnectionError event is fired in response.
NOTE: this method is called automatically when the AVChatManager is instantiated.
Throws:
Events broadcasted to listeners:
  • RedBoxChatEvent with type: onAVConnectionInited
    • Dispatched when the connection to Red5 server has been established.
  • RedBoxChatEvent with type: onAVConnectionError
    • Dispatched when the connection to Red5 server can't be established.
Example:
  • The following example shows how to initialize the Red5 connection for the AVChatManager instance.
    avChatMan.initAVConnection()

refuseChatRequest

function refuseChatRequest (
sessionId:String) : Void

Refuse an incoming request to start an audio/video chat.
Calling this method causes the com.smartfoxserver.redbox.events.RedBoxChatEvent.onChatRefused event to be fired on the requester's client.
Parameters:
sessionId:
the id of the chat session request to be refused (see com.smartfoxserver.redbox.data.ChatSession.id property).
Events broadcasted to listeners:
  • RedBoxChatEvent with type: onChatRefused
    • Dispatched when an a/v chat request has been refused by the recipient.
Throws:
Example:
  • The following example shows how to refuse a chat request.
    bt_decline.addEventListener("click", Delegate.create(this, onDeclineBtClick))
    
    // After receiving a chat request, its session id is saved and a "decline" button activated...
    
    function onDeclineBtClick(evt:MouseEvent):Void
    {
        avChatMan.refuseChatRequest(chatSessionId)
    }

removeEventListener

function removeEventListener (
type:String, listener:Function) : Void

Remove a listener from the event dispatcher, to stop receiving notification of an event.
Parameters:
type :
The event type you registered your listener to.
listener:
The listener function to remove.
Usage:
  • To remove a listener:
    avChatMan.removeEventListener(RedBoxChatEvent.onChatRequest, myListener)
    NOTE: the Delegate.create() is not required to remove a listener.

sendChatRequest

function sendChatRequest (
type:String, recipientId:Number, enableCamera:Boolean, enableMicrophone:Boolean) : ChatSession

Send a request to start an audio/video chat.
When this method is called, a "chat session" is created (see the com.smartfoxserver.redbox.data.ChatSession class description) and an invitation to start the a/v chat is sent to the selected user id, causing the com.smartfoxserver.redbox.events.RedBoxChatEvent.onChatRequest event to be fired on the recipient's client.
If the recipient is not available (for example he disconnects while the request is being sent), the com.smartfoxserver.redbox.events.RedBoxChatEvent.onRecipientMissing event is fired in response.
If the mutual request has already been sent by the recipient, the com.smartfoxserver.redbox.events.RedBoxChatEvent.onDuplicateRequest is fired in response.
Audio and video recording mode/quality should be set before calling this method. In order to alter these settings, please refer to the Microphone and Camera classes documentation.
Parameters:
type :
the request type; valid values are: REQ_TYPE_SEND, REQ_TYPE_RECEIVE and REQ_TYPE_SEND_RECEIVE.
recipientId :
the SmartFoxServer's user id of the recipient.
enableCamera :
enable video live streaming; default value is true.
enableMicrophone:
enable audio live streaming; default value is true.
Returns:
Events broadcasted to listeners:
  • RedBoxChatEvent with type: onChatRequest
    • Dispatched when an a/v chat request is received.
  • RedBoxChatEvent with type: onRecipientMissing
    • Dispatched when a chat request is sent, but the recipient is not available.
  • RedBoxChatEvent with type: onDuplicateRequest
    • Dispatched when a chat request is sent, but a mutual request has already been sent by the recipient.
Throws:
Example:
  • The following example shows how to send a request to start an a/v chat.
    avChatMan.addEventListener(RedBoxChatEvent.onRecipientMissing, Delegate.create(this, onRecipientMissing))
    avChatMan.addEventListener(RedBoxChatEvent.onDuplicateRequest, Delegate.create(this, onDuplicateRequest))
    
    avChatMan.sendChatRequest(AVChatManager.REQ_TYPE_SEND_RECEIVE, buddyId, true, true)
    
    function onRecipientMissing(evt:RedBoxChatEvent):Void
    {
        trace ("Request '" + evt.params.chatSession.id + "' error: the recipient is not available!")
    }
    
    function onDuplicateRequest(evt:RedBoxChatEvent):Void
    {
        trace ("Request '" + evt.params.chatSession.id + "' error: a mutual request has already been sent by the recipient!")
    }

stopChat

function stopChat (
sessionId:String) : Void

Stop an a/v chat session currently in progress.
Calling this method causes the com.smartfoxserver.redbox.events.RedBoxChatEvent.onChatStopped event to be fired on the connected user (mate) clients.
Parameters:
sessionId:
the id of the chat session to be stopped (see com.smartfoxserver.redbox.data.ChatSession.id property).
Events broadcasted to listeners:
  • RedBoxChatEvent with type: onChatStopped
    • Dispatched when an a/v chat session is stopped.
Example:
  • The following example shows how to stop a chat session.
    bt_stop.addEventListener("click", Delegate.create(this, onStopBtClick))
    
    // After the chat session started, a "stop" button is activated...
    
    function onStopBtClick(evt:MouseEvent):Void
    {
        avChatMan.stopChat(chatSessionId)
    }